<!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-util.Format'>/**
</span> * @class Ext.util.Format

This class is a centralized place for formatting functions inside the library. It includes
functions to format various different types of data, such as text, dates and numeric values.

__Localization__
This class contains several options for localization. These can be set once the library has loaded,
all calls to the functions from that point will use the locale settings that were specified.
Options include:
- thousandSeparator
- decimalSeparator
- currenyPrecision
- currencySign
- currencyAtEnd
This class also uses the default date format defined here: {@link Ext.date#defaultFormat}.

__Using with renderers__
There are two helper functions that return a new function that can be used in conjunction with 
grid renderers:

    columns: [{
        dataIndex: 'date',
        renderer: Ext.util.Format.dateRenderer('Y-m-d')
    }, {
        dataIndex: 'time',
        renderer: Ext.util.Format.numberRenderer('0.000')
    }]
    
Functions that only take a single argument can also be passed directly:
    columns: [{
        dataIndex: 'cost',
        renderer: Ext.util.Format.usMoney
    }, {
        dataIndex: 'productCode',
        renderer: Ext.util.Format.uppercase
    }]
    
__Using with XTemplates__
XTemplates can also directly use Ext.util.Format functions:

    new Ext.XTemplate([
        'Date: {startDate:date(&quot;Y-m-d&quot;)}',
        'Cost: {cost:usMoney}'
    ]);

 * @markdown
 * @singleton
 */
(function() {
    Ext.ns('Ext.util');

    Ext.util.Format = {};
    var UtilFormat     = Ext.util.Format,
        stripTagsRE    = /&lt;\/?[^&gt;]+&gt;/gi,
        stripScriptsRe = /(?:&lt;script.*?&gt;)((\n|\r|.)*?)(?:&lt;\/script&gt;)/ig,
        nl2brRe        = /\r?\n/g,

        // A RegExp to remove from a number format string, all characters except digits and '.'
        formatCleanRe  = /[^\d\.]/g,

        // A RegExp to remove from a number format string, all characters except digits and the local decimal separator.
        // Created on first use. The local decimal separator character must be initialized for this to be created.
        I18NFormatCleanRe;

    Ext.apply(UtilFormat, {
<span id='Ext-util.Format-property-thousandSeparator'>        /**
</span>         * @type String
         * @property thousandSeparator
         * &lt;p&gt;The character that the {@link #number} function uses as a thousand separator.&lt;/p&gt;
         * &lt;p&gt;This defaults to &lt;code&gt;,&lt;/code&gt;, but may be overridden in a locale file.&lt;/p&gt;
         */
        thousandSeparator: ',',

<span id='Ext-util.Format-property-decimalSeparator'>        /**
</span>         * @type String
         * @property decimalSeparator
         * &lt;p&gt;The character that the {@link #number} function uses as a decimal point.&lt;/p&gt;
         * &lt;p&gt;This defaults to &lt;code&gt;.&lt;/code&gt;, but may be overridden in a locale file.&lt;/p&gt;
         */
        decimalSeparator: '.',

<span id='Ext-util.Format-property-currencyPrecision'>        /**
</span>         * @type Number
         * @property currencyPrecision
         * &lt;p&gt;The number of decimal places that the {@link #currency} function displays.&lt;/p&gt;
         * &lt;p&gt;This defaults to &lt;code&gt;2&lt;/code&gt;, but may be overridden in a locale file.&lt;/p&gt;
         */
        currencyPrecision: 2,

<span id='Ext-util.Format-property-currencySign'>        /**
</span>         * @type String
         * @property currencySign
         * &lt;p&gt;The currency sign that the {@link #currency} function displays.&lt;/p&gt;
         * &lt;p&gt;This defaults to &lt;code&gt;$&lt;/code&gt;, but may be overridden in a locale file.&lt;/p&gt;
         */
        currencySign: '$',

<span id='Ext-util.Format-property-currencyAtEnd'>        /**
</span>         * @type Boolean
         * @property currencyAtEnd
         * &lt;p&gt;This may be set to &lt;code&gt;true&lt;/code&gt; to make the {@link #currency} function
         * append the currency sign to the formatted value.&lt;/p&gt;
         * &lt;p&gt;This defaults to &lt;code&gt;false&lt;/code&gt;, but may be overridden in a locale file.&lt;/p&gt;
         */
        currencyAtEnd: false,

<span id='Ext-util.Format-method-undef'>        /**
</span>         * Checks a reference and converts it to empty string if it is undefined
         * @param {Mixed} value Reference to check
         * @return {Mixed} Empty string if converted, otherwise the original value
         */
        undef : function(value) {
            return value !== undefined ? value : &quot;&quot;;
        },

<span id='Ext-util.Format-method-defaultValue'>        /**
</span>         * Checks a reference and converts it to the default value if it's empty
         * @param {Mixed} value Reference to check
         * @param {String} defaultValue The value to insert of it's undefined (defaults to &quot;&quot;)
         * @return {String}
         */
        defaultValue : function(value, defaultValue) {
            return value !== undefined &amp;&amp; value !== '' ? value : defaultValue;
        },

<span id='Ext-util.Format-method-substr'>        /**
</span>         * Returns a substring from within an original string
         * @param {String} value The original text
         * @param {Number} start The start index of the substring
         * @param {Number} length The length of the substring
         * @return {String} The substring
         */
        substr : function(value, start, length) {
            return String(value).substr(start, length);
        },

<span id='Ext-util.Format-method-lowercase'>        /**
</span>         * Converts a string to all lower case letters
         * @param {String} value The text to convert
         * @return {String} The converted text
         */
        lowercase : function(value) {
            return String(value).toLowerCase();
        },

<span id='Ext-util.Format-method-uppercase'>        /**
</span>         * Converts a string to all upper case letters
         * @param {String} value The text to convert
         * @return {String} The converted text
         */
        uppercase : function(value) {
            return String(value).toUpperCase();
        },

<span id='Ext-util.Format-method-usMoney'>        /**
</span>         * Format a number as US currency
         * @param {Number/String} value The numeric value to format
         * @return {String} The formatted currency string
         */
        usMoney : function(v) {
            return UtilFormat.currency(v, '$', 2);
        },

<span id='Ext-util.Format-method-currency'>        /**
</span>         * Format a number as a currency
         * @param {Number/String} value The numeric value to format
         * @param {String} sign The currency sign to use (defaults to {@link #currencySign})
         * @param {Number} decimals The number of decimals to use for the currency (defaults to {@link #currencyPrecision})
         * @param {Boolean} end True if the currency sign should be at the end of the string (defaults to {@link #currencyAtEnd})
         * @return {String} The formatted currency string
         */
        currency: function(v, currencySign, decimals, end) {
            var negativeSign = '',
                format = &quot;,0&quot;,
                i = 0;
            v = v - 0;
            if (v &lt; 0) {
                v = -v;
                negativeSign = '-';
            }
            decimals = decimals || UtilFormat.currencyPrecision;
            format += format + (decimals &gt; 0 ? '.' : '');
            for (; i &lt; decimals; i++) {
                format += '0';
            }
            v = UtilFormat.number(v, format); 
            if ((end || UtilFormat.currencyAtEnd) === true) {
                return Ext.String.format(&quot;{0}{1}{2}&quot;, negativeSign, v, currencySign || UtilFormat.currencySign);
            } else {
                return Ext.String.format(&quot;{0}{1}{2}&quot;, negativeSign, currencySign || UtilFormat.currencySign, v);
            }
        },

<span id='Ext-util.Format-method-date'>        /**
</span>         * Formats the passed date using the specified format pattern.
         * @param {String/Date} value The value to format. If a string is passed, it is converted to a Date by the Javascript
         * Date object's &lt;a href=&quot;http://www.w3schools.com/jsref/jsref_parse.asp&quot;&gt;parse()&lt;/a&gt; method.
         * @param {String} format (Optional) Any valid date format string. Defaults to {@link Ext.Date#defaultFormat}.
         * @return {String} The formatted date string.
         */
        date: function(v, format) {
            if (!v) {
                return &quot;&quot;;
            }
            if (!Ext.isDate(v)) {
                v = new Date(Date.parse(v));
            }
            return Ext.Date.dateFormat(v, format || Ext.Date.defaultFormat);
        },

<span id='Ext-util.Format-method-dateRenderer'>        /**
</span>         * Returns a date rendering function that can be reused to apply a date format multiple times efficiently
         * @param {String} format Any valid date format string. Defaults to {@link Ext.Date#defaultFormat}.
         * @return {Function} The date formatting function
         */
        dateRenderer : function(format) {
            return function(v) {
                return UtilFormat.date(v, format);
            };
        },

<span id='Ext-util.Format-method-stripTags'>        /**
</span>         * Strips all HTML tags
         * @param {Mixed} value The text from which to strip tags
         * @return {String} The stripped text
         */
        stripTags : function(v) {
            return !v ? v : String(v).replace(stripTagsRE, &quot;&quot;);
        },

<span id='Ext-util.Format-method-stripScripts'>        /**
</span>         * Strips all script tags
         * @param {Mixed} value The text from which to strip script tags
         * @return {String} The stripped text
         */
        stripScripts : function(v) {
            return !v ? v : String(v).replace(stripScriptsRe, &quot;&quot;);
        },

<span id='Ext-util.Format-method-fileSize'>        /**
</span>         * Simple format for a file size (xxx bytes, xxx KB, xxx MB)
         * @param {Number/String} size The numeric value to format
         * @return {String} The formatted file size
         */
        fileSize : function(size) {
            if (size &lt; 1024) {
                return size + &quot; bytes&quot;;
            } else if (size &lt; 1048576) {
                return (Math.round(((size*10) / 1024))/10) + &quot; KB&quot;;
            } else {
                return (Math.round(((size*10) / 1048576))/10) + &quot; MB&quot;;
            }
        },

<span id='Ext-util.Format-method-math'>        /**
</span>         * It does simple math for use in a template, for example:&lt;pre&gt;&lt;code&gt;
         * var tpl = new Ext.Template('{value} * 10 = {value:math(&quot;* 10&quot;)}');
         * &lt;/code&gt;&lt;/pre&gt;
         * @return {Function} A function that operates on the passed value.
         */
        math : function(){
            var fns = {};

            return function(v, a){
                if (!fns[a]) {
                    fns[a] = Ext.functionFactory('v', 'return v ' + a + ';');
                }
                return fns[a](v);
            };
        }(),

<span id='Ext-util.Format-method-round'>        /**
</span>         * Rounds the passed number to the required decimal precision.
         * @param {Number/String} value The numeric value to round.
         * @param {Number} precision The number of decimal places to which to round the first parameter's value.
         * @return {Number} The rounded value.
         */
        round : function(value, precision) {
            var result = Number(value);
            if (typeof precision == 'number') {
                precision = Math.pow(10, precision);
                result = Math.round(value * precision) / precision;
            }
            return result;
        },

<span id='Ext-util.Format-method-number'>        /**
</span>         * &lt;p&gt;Formats the passed number according to the passed format string.&lt;/p&gt;
         * &lt;p&gt;The number of digits after the decimal separator character specifies the number of
         * decimal places in the resulting string. The &lt;u&gt;local-specific&lt;/u&gt; decimal character is used in the result.&lt;/p&gt;
         * &lt;p&gt;The &lt;i&gt;presence&lt;/i&gt; of a thousand separator character in the format string specifies that
         * the &lt;u&gt;locale-specific&lt;/u&gt; thousand separator (if any) is inserted separating thousand groups.&lt;/p&gt;
         * &lt;p&gt;By default, &quot;,&quot; is expected as the thousand separator, and &quot;.&quot; is expected as the decimal separator.&lt;/p&gt;
         * &lt;p&gt;&lt;b&gt;New to Ext4&lt;/b&gt;&lt;/p&gt;
         * &lt;p&gt;Locale-specific characters are always used in the formatted output when inserting
         * thousand and decimal separators.&lt;/p&gt;
         * &lt;p&gt;The format string must specify separator characters according to US/UK conventions (&quot;,&quot; as the
         * thousand separator, and &quot;.&quot; as the decimal separator)&lt;/p&gt;
         * &lt;p&gt;To allow specification of format strings according to local conventions for separator characters, add
         * the string &lt;code&gt;/i&lt;/code&gt; to the end of the format string.&lt;/p&gt;
         * &lt;div style=&quot;margin-left:40px&quot;&gt;examples (123456.789):
         * &lt;div style=&quot;margin-left:10px&quot;&gt;
         * 0 - (123456) show only digits, no precision&lt;br&gt;
         * 0.00 - (123456.78) show only digits, 2 precision&lt;br&gt;
         * 0.0000 - (123456.7890) show only digits, 4 precision&lt;br&gt;
         * 0,000 - (123,456) show comma and digits, no precision&lt;br&gt;
         * 0,000.00 - (123,456.78) show comma and digits, 2 precision&lt;br&gt;
         * 0,0.00 - (123,456.78) shortcut method, show comma and digits, 2 precision&lt;br&gt;
         * To allow specification of the formatting string using UK/US grouping characters (,) and decimal (.) for international numbers, add /i to the end.
         * For example: 0.000,00/i
         * &lt;/div&gt;&lt;/div&gt;
         * @param {Number} v The number to format.
         * @param {String} format The way you would like to format this text.
         * @return {String} The formatted number.
         */
        number:
            function(v, formatString) {
            if (!formatString) {
                return v;
            }
            v = Ext.Number.from(v, NaN);
            if (isNaN(v)) {
                return '';
            }
            var comma = UtilFormat.thousandSeparator,
                dec   = UtilFormat.decimalSeparator,
                i18n  = false,
                neg   = v &lt; 0,
                hasComma,
                psplit;

            v = Math.abs(v);

            // The &quot;/i&quot; suffix allows caller to use a locale-specific formatting string.
            // Clean the format string by removing all but numerals and the decimal separator.
            // Then split the format string into pre and post decimal segments according to *what* the
            // decimal separator is. If they are specifying &quot;/i&quot;, they are using the local convention in the format string.
            if (formatString.substr(formatString.length - 2) == '/i') {
                if (!I18NFormatCleanRe) {
                    I18NFormatCleanRe = new RegExp('[^\\d\\' + UtilFormat.decimalSeparator + ']','g');
                }
                formatString = formatString.substr(0, formatString.length - 2);
                i18n   = true;
                hasComma = formatString.indexOf(comma) != -1;
                psplit = formatString.replace(I18NFormatCleanRe, '').split(dec);
            } else {
                hasComma = formatString.indexOf(',') != -1;
                psplit = formatString.replace(formatCleanRe, '').split('.');
            }

            if (1 &lt; psplit.length) {
                v = v.toFixed(psplit[1].length);
            } else if(2 &lt; psplit.length) {
                //&lt;debug&gt;
                Ext.Error.raise({
                    sourceClass: &quot;Ext.util.Format&quot;,
                    sourceMethod: &quot;number&quot;,
                    value: v,
                    formatString: formatString,
                    msg: &quot;Invalid number format, should have no more than 1 decimal&quot;
                });
                //&lt;/debug&gt;
            } else {
                v = v.toFixed(0);
            }

            var fnum = v.toString();

            psplit = fnum.split('.');

            if (hasComma) {
                var cnum = psplit[0],
                    parr = [],
                    j    = cnum.length,
                    m    = Math.floor(j / 3),
                    n    = cnum.length % 3 || 3,
                    i;

                for (i = 0; i &lt; j; i += n) {
                    if (i !== 0) {
                        n = 3;
                    }

                    parr[parr.length] = cnum.substr(i, n);
                    m -= 1;
                }
                fnum = parr.join(comma);
                if (psplit[1]) {
                    fnum += dec + psplit[1];
                }
            } else {
                if (psplit[1]) {
                    fnum = psplit[0] + dec + psplit[1];
                }
            }

            return (neg ? '-' : '') + formatString.replace(/[\d,?\.?]+/, fnum);
        },

<span id='Ext-util.Format-method-numberRenderer'>        /**
</span>         * Returns a number rendering function that can be reused to apply a number format multiple times efficiently
         * @param {String} format Any valid number format string for {@link #number}
         * @return {Function} The number formatting function
         */
        numberRenderer : function(format) {
            return function(v) {
                return UtilFormat.number(v, format);
            };
        },

<span id='Ext-util.Format-method-plural'>        /**
</span>         * Selectively do a plural form of a word based on a numeric value. For example, in a template,
         * {commentCount:plural(&quot;Comment&quot;)}  would result in &quot;1 Comment&quot; if commentCount was 1 or would be &quot;x Comments&quot;
         * if the value is 0 or greater than 1.
         * @param {Number} value The value to compare against
         * @param {String} singular The singular form of the word
         * @param {String} plural (optional) The plural form of the word (defaults to the singular with an &quot;s&quot;)
         */
        plural : function(v, s, p) {
            return v +' ' + (v == 1 ? s : (p ? p : s+'s'));
        },

<span id='Ext-util.Format-method-nl2br'>        /**
</span>         * Converts newline characters to the HTML tag &amp;lt;br/&gt;
         * @param {String} The string value to format.
         * @return {String} The string with embedded &amp;lt;br/&gt; tags in place of newlines.
         */
        nl2br : function(v) {
            return Ext.isEmpty(v) ? '' : v.replace(nl2brRe, '&lt;br/&gt;');
        },

<span id='Ext-util.Format-property-capitalize'>        /**
</span>         * Capitalize the given string. See {@link Ext.String#capitalize}.
         */
        capitalize: Ext.String.capitalize,

<span id='Ext-util.Format-property-ellipsis'>        /**
</span>         * Truncate a string and add an ellipsis ('...') to the end if it exceeds the specified length.
         * See {@link Ext.String#ellipsis}.
         */
        ellipsis: Ext.String.ellipsis,

<span id='Ext-util.Format-property-format'>        /**
</span>         * Formats to a string. See {@link Ext.String#format}
         */
        format: Ext.String.format,

<span id='Ext-util.Format-property-htmlDecode'>        /**
</span>         * Convert certain characters (&amp;, &lt;, &gt;, and ') from their HTML character equivalents.
         * See {@link Ext.string#htmlDecode}.
         */
        htmlDecode: Ext.String.htmlDecode,

<span id='Ext-util.Format-property-htmlEncode'>        /**
</span>         * Convert certain characters (&amp;, &lt;, &gt;, and ') to their HTML character equivalents for literal display in web pages.
         * See {@link Ext.String#htmlEncode}.
         */
        htmlEncode: Ext.String.htmlEncode,

<span id='Ext-util.Format-property-leftPad'>        /**
</span>         * Adds left padding to a string. See {@link Ext.String#leftPad}
         */
        leftPad: Ext.String.leftPad,

<span id='Ext-util.Format-property-trim'>        /**
</span>         * Trims any whitespace from either side of a string. See {@link Ext.String#trim}.
         */
        trim : Ext.String.trim,

<span id='Ext-util.Format-method-parseBox'>        /**
</span>         * Parses a number or string representing margin sizes into an object. Supports CSS-style margin declarations
         * (e.g. 10, &quot;10&quot;, &quot;10 10&quot;, &quot;10 10 10&quot; and &quot;10 10 10 10&quot; are all valid options and would return the same result)
         * @param {Number|String} v The encoded margins
         * @return {Object} An object with margin sizes for top, right, bottom and left
         */
        parseBox : function(box) {
            if (Ext.isNumber(box)) {
                box = box.toString();
            }
            var parts  = box.split(' '),
                ln = parts.length;

            if (ln == 1) {
                parts[1] = parts[2] = parts[3] = parts[0];
            }
            else if (ln == 2) {
                parts[2] = parts[0];
                parts[3] = parts[1];
            }
            else if (ln == 3) {
                parts[3] = parts[1];
            }

            return {
                top   :parseInt(parts[0], 10) || 0,
                right :parseInt(parts[1], 10) || 0,
                bottom:parseInt(parts[2], 10) || 0,
                left  :parseInt(parts[3], 10) || 0
            };
        },

<span id='Ext-util.Format-method-escapeRegex'>        /**
</span>         * Escapes the passed string for use in a regular expression
         * @param {String} str
         * @return {String}
         */
        escapeRegex : function(s) {
            return s.replace(/([\-.*+?\^${}()|\[\]\/\\])/g, &quot;\\$1&quot;);
        }
    });
})();
</pre></pre></body></html>